Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

Installing and Configuring SSL Support

What is Secure Socket Layer Technology?

Secure Socket Layer (SSL) is a technology that allows Web browsers and Web servers to communicate over a secured connection. In this secure connection, the data that is being sent is encrypted before being sent, then decrypted upon receipt and prior to processing. Both the browser and the server encrypt all traffic before sending any data. SSL addresses the following important security considerations.

Setting Up Digital Certificates

In order to use SSL, a J2EE server must have an associated certificate for each external interface, or IP address, that accepts secure connections. The theory behind this design is that a server should provide some kind of reasonable assurance that its owner is who you think it is, particularly before receiving any sensitive information. It may be useful to think of a certificate as a "digital driver's license" for an Internet address. It states with which company the site is associated, along with some basic contact information about the site owner or administrator.

The digital certificate is cryptographically signed by its owner and is difficult for anyone else to forge. For sites involved in e-commerce, or any other business transaction in which authentication of identity is important, a certificate can be purchased from a well-known Certificate Authority (CA) such as Verisign or Thawte.

If authentication is not really a concern, such as if an administrator simply wants to ensure that data being transmitted and received by the server is private and cannot be snooped by anyone eavesdropping on the connection, you can simply save the time and expense involved in obtaining a CA certificate and simply use a self-signed certificate.

SSL uses public key cryptography, which is based on key pairs. Key pairs contain one public key and one private key. If data is encrypted with one key, it can only be decrypted with the other key of the pair. This property of is fundamental to establishing trust and privacy in transactions. For example, using SSL, the server computes a value and encrypts the value using its private key. The encrypted value is called a digital signature. The client decrypts the encrypted value using the server's public key and compares the value to its own computed value. If the two values match, the client can trust that the signature is authentic since only the private key could have been used to produce such a signature.

Digital certificates are used with the HTTPS protocol to authenticate Web clients. The HTTPS service of most Web servers will not run unless a digital certificate has been installed. Use the procedure outlined below to set up a digital certificate that can be used by your Web server to enable SSL.

One tool that can be used to set up a digital certificate is keytool, a key and certificate management utility that ships with J2EE 1.4 Application Server. It enables users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself/herself to other users/services) or data integrity and authentication services, using digital signatures. It also allows users to cache the public keys (in the form of certificates) of their communicating peers. For a better understanding of public key cryptography, read the keytool documentation at http://java.sun.com/j2se/1.4.1/docs/tooldocs/solaris/keytool.html.

A certificate is a digitally-signed statement from one entity (person, company, etc.), saying that the public key (and some other information) of some other entity has a particular value. When data is digitally signed, the signature can be verified to check the data integrity and authenticity. Integrity means that the data has not been modified or tampered with, and authenticity means the data indeed comes from whoever claims to have created and signed it.

The keytool stores the keys and certificates in a file termed a keystore. The default keystore implementation implements the keystore as a file. It protects private keys with a password. For more information on keytool, read its documentation at http://java.sun.com/j2se/1.4.1/docs/tooldocs/solaris/keytool.html.

You can create a self-signed certificate by following the instructions in Creating a Client Certificate for Mutual Authentication.

Creating a Client Certificate for Mutual Authentication

To create a client certificate:

  1. Use keytool to create a client certificate in a keystore file of your choice:
  2. keytool -genkey -keyalg RSA -alias client -keystore
    client.keystore

    You will be prompted for a password. Enter changeit, the default password. When requested, enter the name, organization, and other prompts for the client. Do not enter anything at the Key password for <client> prompt, just press Return.

  3. Export the new client certificate from the keystore to a certificate file:
  4. keytool -keystore client.keystore -export -alias client
    -file client.cer

  5. Enter the keystore password (changeit). Keytool returns this message:
  6. Certificate stored in file <client.cer>

  7. Import the new client certificate into the server's trustStore file <J2EE_HOME>/domains/domain1/server/config/cacerts.jks. This allows the server to trust the client during SSL mutual authentication.
  8. keytool -import -alias root -keystore $J2EE_HOME/domains/domain1/server/config/ cacerts.jks
    -file client.cer

  9. Enter the keystore password (changeit). Keytool returns this message:
  10. Owner: CN=J2EE Client, OU=Java Web Services, O=Sun, L=Santa Clara, ST=CA, C=US
    Issuer: CN=J2EE Client, OU=Java Web Services, O=Sun, L=Santa Clara, ST=CA, C=US
    Serial number: 3e39e66a
    Valid from: Thu Jan 30 18:58:50 PST 2003 until: Wed Apr 30
    19:58:50 PDT 2003
    Certificate fingerprints:
    MD5: 5A:B0:4C:88:4E:F8:EF:E9:E5:8B:53:BD:D0:AA:8E:5A
    SHA1:90:00:36:5B:E0:A7:A2:BD:67:DB:EA:37:B9:61:3E:26:B3:89:46:
    32
    Trust this certificate? [no]: yes
    Certificate was added to keystore

For an example application that uses mutual authentication, see Configuring Mutual Authentication, page 813. For information on verifying that mutual authentication is running, see Verifying Mutual Authentication is Running.

Obtaining a Digitally-Signed Certificate

This example assumes a keystore named client.keystore (created in Creating a Client Certificate for Mutual Authentication) and the certificate request file csr_filename.

  1. Get your certificate digitally signed by a CA. To do this,
    1. Generate a Certificate Signing Request (CSR).
    2. keytool -certreq -alias client -keyalg RSA
        -file <csr_filename> -keystore client.keystore

    3. Send the contents of the csr_filename for signing.
    4. If you are using Verisign CA, go to http://digitalid.verisign.com/. Verisign will send the signed certificate in E-mail. Store this certificate in a file.
    5. Import the signed certificate that you received in E-mail into the server's trustStore:
    6. keytool -import -alias client -trustcacerts -file
        <signed_cert_file> -keystore
        <J2EE_HOME>/domains/domain1/server/config/cacerts.jks

  2. Import the certificate (if using a CA-signed certificate).
  3. If your certificate will be signed by a Certification Authority (CA), you must import the CA certificate. You may skip this step if you are using only the self-signed certificate. If you are using a self-signed certificate or a certificate signed by a CA that your browser does not recognize, a dialog will be triggered the first time a user tries to access the server. The user can then choose to trust the certificate for this session only or permanently.

Verifying Mutual Authentication is Running

You can verify that mutual authentication is working by obtaining debug messages. This should be done at the client end, and this examples shows how to pass a system property in targets.xml so that targets.xml forks a client with javax.net.debug in its system properties.

To enable debug messages for SSL mutual authentication, pass the system property javax.net.debug=ssl,handshake, which will provide information on whether mutual authentication is working or not. This can be done by adding the sysproperty to targets.xml file as shown in bold:

    <java 
      fork="on" 
      classpath="${dist}/${client-jar}:${j2ee-path}" 
      classname="${client-class}" >
      <arg value="${trustStore}" />
      <arg value="${trustStorePassword}" />
      <arg value="${key-store}" />
      <arg value="${key-store-password}" />
      <arg value="${endpoint-address}" />
      <sysproperty key="javax.net.debug"
        value="ssl,handshake" />
      <sysproperty key="javax.net.ssl.keyStore" 
        value="${key-store}" />
      <sysproperty key="javax.net.ssl.keyStorePassword"
        value="${key-store-password}" /
    </java> 

Miscellaneous Commands for Certificates

Verifying SSL Support

For testing purposes, and to verify that SSL support has been correctly installed, load the default introduction page with a URL that connects to port defined in the server deployment descriptor:

https://localhost:1043/ 

The https in this URL indicates that the browser should be using the SSL protocol.

The first time a user loads this application, the New Site Certificate dialog displays. Select Next to move through the series of New Site Certificate dialogs, select Finish when you reach the last dialog. The certificates will only display the first time. When you accept the certificates, subsequent hits to this site assume that you still trust the content.

General Tips on Running SSL

The SSL protocol is designed to be as efficient as securely possible. However, encryption/decryption is a computationally expensive process from a performance standpoint. It is not strictly necessary to run an entire Web application over SSL, and it is customary for a developer to decide which pages require a secure connection and which do not. Pages that might require a secure connection include login pages, personal information pages, shopping cart checkouts, or any pages where credit card information could possibly be transmitted. Any page within an application can be requested over a secure socket by simply prefixing the address with https: instead of http:. Any pages which absolutely require a secure connection should check the protocol type associated with the page request and take the appropriate action if https: is not specified.

Using name-based virtual hosts on a secured connection can be problematic. This is a design limitation of the SSL protocol itself. The SSL handshake, where the client browser accepts the server certificate, must occur before the HTTP request is accessed. As a result, the request information containing the virtual host name cannot be determined prior to authentication, and it is therefore not possible to assign multiple certificates to a single IP address. If all virtual hosts on a single IP address need to authenticate against the same certificate, the addition of multiple virtual hosts should not interfere with normal SSL operations on the server. Be aware, however, that most client browsers will compare the server's domain name against the domain name listed in the certificate, if any (applicable primarily to official, CA-signed certificates). If the domain names do not match, these browsers will display a warning to the client. In general, only address-based virtual hosts are commonly used with SSL in a production environment.

Divider
Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

All of the material in The J2EE 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.